---
id: change-password
title: Change Password
---

:::tip Before you start

Please read the
[Username / Email & Password Credentials Documentation](../../../concepts/credentials/username-email-password.mdx)
and [User Settings Documentation](../user-settings.mdx) first.

:::

This document summarizes exemplary request payloads for performing "change password" flows
using the user settings flow with the `password` strategy.

ORY Kratos will prompt the user to re-authenticate before the password is changed, similar to the
[GitHub sudo mode](https://help.github.com/en/github/authenticating-to-github/sudo-mode).

You can configure how long a session is "privileged" by setting:

```yaml title="path/to/kratos/config.yml"
selfservice:
  settings:
    # Sessions older than a minute requires the user to sign in again before
    # the password is changed.
    privileged_session_max_age: 1m
```

## Browser Clients

Redirecting the browser to the [Self-Service Settings Endpoint](../user-settings.mdx#user-settings-process-sequence)
initiates the flow. If the `password` strategy is enabled, the Settings Request Response Payload will include a `password` method:

```json5 title="$ curl http://<kratos-admin>/self-service/browser/flows/requests/settings?request=71da1753-e135-441c-b4df-e7b7cd90ad88"
{
  "id": "71da1753-e135-441c-b4df-e7b7cd90ad88",
  "expires_at": "2020-05-02T15:52:09.67209Z",
  "issued_at": "2020-05-02T14:52:09.67209Z",
  "request_url": "http://127.0.0.1:4433/self-service/browser/flows/settings",
  "methods": {
    // "profile": ...
    // "oidc": ...
    "password": {
      "method": "password",
      "config": {
        "action": "http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/settings/strategies/password?request=71da1753-e135-441c-b4df-e7b7cd90ad88",
        "method": "POST",
        "fields": [
          {
            "name": "password",
            "type": "password",
            "required": true
          },
          {
            "name": "csrf_token",
            "type": "hidden",
            "required": true,
            "value": "UjEPiUMubRiAl0NG7yUzsww8XjpJvW+HBrh6JirjLxPqhlW2ql+0kYknjd8gdsx0v08vQSmqUEcZhNPsvkr2Kw=="
          }
        ]
      }
    }
  },
  "identity": {
    "id": "f48c43bb-50ea-4520-9280-37a891175aba",
    "traits": {
      "email": "h71x9a@j6r8c"
    }
  },
  "update_successful": false
}
```

Once submitted, the password is validated. If validation fails, the reason will be included:

```json5 title="$ curl http://<kratos-admin>/self-service/browser/flows/requests/settings?request=71da1753-e135-441c-b4df-e7b7cd90ad88"
{
  id: '71da1753-e135-441c-b4df-e7b7cd90ad88',
  // expires_at, ...
  active: 'password', // <- this is now set!
  methods: {
    password: {
      method: "password",
      config: {
        // action, method ...
        errors: [
          {
            message: 'Please check the data you provided.',
          },
        ],
        fields: [
          // ...
          {
            name: 'password',
            type: 'password',
            required: true,
            errors: [
              {
                message: 'password: password is required',
              },
            ],
          },
        ],
      },
    },
  },
  // identity, ...
  update_successful: false,
}
```

A successful flow will be marked with:

```json5 title="$ curl http://<kratos-admin>/self-service/browser/flows/requests/settings?request=71da1753-e135-441c-b4df-e7b7cd90ad88"
{
  id: '71da1753-e135-441c-b4df-e7b7cd90ad88',
  // expires_at, active, methods, ...
  update_successful: true,
}
```

## API Clients

API-based login and registration using this strategy will be addressed in a
future release of ORY Kratos.

## Security and Defenses

Please head over to [Username / Email and Password Security and Defenses](../user-login-user-registration/username-email-password.mdx#security-and-defenses)
